home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / app.h next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  5.5 KB  |  213 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1999-2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: app.h,v 1.2.18.2 2005/04/29 00:16:52 marka Exp $ */
  19.  
  20. #ifndef ISC_APP_H
  21. #define ISC_APP_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  * \brief ISC Application Support
  29.  *
  30.  * Dealing with program termination can be difficult, especially in a
  31.  * multithreaded program.  The routines in this module help coordinate
  32.  * the shutdown process.  They are used as follows by the initial (main)
  33.  * thread of the application:
  34.  *
  35.  *\li        isc_app_start();    Call very early in main(), before
  36.  *                    any other threads have been created.
  37.  *
  38.  *\li        isc_app_run();        This will post any on-run events,
  39.  *                    and then block until application
  40.  *                    shutdown is requested.  A shutdown
  41.  *                    request is made by calling
  42.  *                    isc_app_shutdown(), or by sending
  43.  *                    SIGINT or SIGTERM to the process.
  44.  *                    After isc_app_run() returns, the
  45.  *                    application should shutdown itself.
  46.  *
  47.  *\li        isc_app_finish();    Call very late in main().
  48.  *
  49.  * Applications that want to use SIGHUP/isc_app_reload() to trigger reloading
  50.  * should check the result of isc_app_run() and call the reload routine if
  51.  * the result is ISC_R_RELOAD.  They should then call isc_app_run() again
  52.  * to resume waiting for reload or termination.
  53.  *
  54.  * Use of this module is not required.  In particular, isc_app_start() is
  55.  * NOT an ISC library initialization routine.
  56.  *
  57.  * \li MP:
  58.  *    Clients must ensure that isc_app_start(), isc_app_run(), and
  59.  *    isc_app_finish() are called at most once.  isc_app_shutdown()
  60.  *    is safe to use by any thread (provided isc_app_start() has been
  61.  *    called previously).
  62.  *
  63.  * \li Reliability:
  64.  *    No anticipated impact.
  65.  *
  66.  * \li Resources:
  67.  *    None.
  68.  *
  69.  * \li Security:
  70.  *    No anticipated impact.
  71.  *
  72.  * \li Standards:
  73.  *    None.
  74.  */
  75.  
  76. #include <isc/eventclass.h>
  77. #include <isc/lang.h>
  78. #include <isc/result.h>
  79.  
  80. typedef isc_event_t isc_appevent_t;
  81.  
  82. #define ISC_APPEVENT_FIRSTEVENT        (ISC_EVENTCLASS_APP + 0)
  83. #define ISC_APPEVENT_SHUTDOWN        (ISC_EVENTCLASS_APP + 1)
  84. #define ISC_APPEVENT_LASTEVENT        (ISC_EVENTCLASS_APP + 65535)
  85.  
  86. ISC_LANG_BEGINDECLS
  87.  
  88. isc_result_t
  89. isc_app_start(void);
  90. /*!<
  91.  * \brief Start an ISC library application.
  92.  *
  93.  * Notes:
  94.  *    This call should be made before any other ISC library call, and as
  95.  *    close to the beginning of the application as possible.
  96.  */
  97.  
  98. isc_result_t
  99. isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action,
  100.           void *arg);
  101. /*!<
  102.  * \brief Request delivery of an event when the application is run.
  103.  *
  104.  * Requires:
  105.  *    isc_app_start() has been called.
  106.  *
  107.  * Returns:
  108.  *    ISC_R_SUCCESS
  109.  *    ISC_R_NOMEMORY
  110.  */
  111.  
  112. isc_result_t
  113. isc_app_run(void);
  114. /*!<
  115.  * \brief Run an ISC library application.
  116.  *
  117.  * Notes:
  118.  *\li    The caller (typically the initial thread of an application) will
  119.  *    block until shutdown is requested.  When the call returns, the
  120.  *    caller should start shutting down the application.
  121.  *
  122.  * Requires:
  123.  *\li    isc_app_start() has been called.
  124.  *
  125.  * Ensures:
  126.  *\li    Any events requested via isc_app_onrun() will have been posted (in
  127.  *    FIFO order) before isc_app_run() blocks.
  128.  *
  129.  * Returns:
  130.  *\li    ISC_R_SUCCESS            Shutdown has been requested.
  131.  *\li    ISC_R_RELOAD            Reload has been requested.
  132.  */
  133.  
  134. isc_result_t
  135. isc_app_shutdown(void);
  136. /*!<
  137.  * \brief Request application shutdown.
  138.  *
  139.  * Notes:
  140.  *\li    It is safe to call isc_app_shutdown() multiple times.  Shutdown will
  141.  *    only be triggered once.
  142.  *
  143.  * Requires:
  144.  *\li    isc_app_run() has been called.
  145.  *
  146.  * Returns:
  147.  *\li    ISC_R_SUCCESS
  148.  *\li    ISC_R_UNEXPECTED
  149.  */
  150.  
  151. isc_result_t
  152. isc_app_reload(void);
  153. /*!<
  154.  * \brief Request application reload.
  155.  *
  156.  * Requires:
  157.  *\li    isc_app_run() has been called.
  158.  *
  159.  * Returns:
  160.  *\li    ISC_R_SUCCESS
  161.  *\li    ISC_R_UNEXPECTED
  162.  */
  163.  
  164. void
  165. isc_app_finish(void);
  166. /*!<
  167.  * \brief Finish an ISC library application.
  168.  *
  169.  * Notes:
  170.  *\li    This call should be made at or near the end of main().
  171.  *
  172.  * Requires:
  173.  *\li    isc_app_start() has been called.
  174.  *
  175.  * Ensures:
  176.  *\li    Any resources allocated by isc_app_start() have been released.
  177.  */
  178.  
  179. void
  180. isc_app_block(void);
  181. /*!<
  182.  * \brief Indicate that a blocking operation will be performed.
  183.  *
  184.  * Notes:
  185.  *\li    If a blocking operation is in process, a call to isc_app_shutdown()
  186.  *    or an external signal will abort the program, rather than allowing
  187.  *    clean shutdown.  This is primarily useful for reading user input.
  188.  *
  189.  * Requires:
  190.  * \li    isc_app_start() has been called.
  191.  * \li    No other blocking operations are in progress.
  192.  */
  193.  
  194. void
  195. isc_app_unblock(void);
  196. /*!<
  197.  * \brief Indicate that a blocking operation is complete.
  198.  *
  199.  * Notes:
  200.  * \li    When a blocking operation has completed, return the program to a
  201.  *     state where a call to isc_app_shutdown() or an external signal will
  202.  *     shutdown normally.
  203.  *
  204.  * Requires:
  205.  * \li    isc_app_start() has been called.
  206.  * \li    isc_app_block() has been called by the same thread.
  207.  */
  208.  
  209.  
  210. ISC_LANG_ENDDECLS
  211.  
  212. #endif /* ISC_APP_H */
  213.